9.1.3.1 Template elements
Now lets look at the elements of a template definition. Each
entry in org-capture-templates is a list with the
following items:
- keys
-
The keys that will select the template, as a string,
characters only, for example
"a" for a template
to be selected with a single key, or "bt" for
selection with two keys. When using several keys, keys using
the same prefix key must be sequential in the list and
preceded by a 2-element entry explaining the prefix key, for
example
("b" "Templates for marking stuff to buy")
If you do not define a template for the
C key, this key will be used to open the customize
buffer for this complex variable.
- description
- A short string describing the template, which will be shown
during selection.
- type
-
The type of entry, a symbol. Valid values are:
entry- An Org-mode node, with a headline. Will be filed as the
child of the target entry or as a top-level entry. The
target file should be an Org-mode file.
item- A plain list item, placed in the first plain list at
the target location. Again the target file should be an Org
file.
checkitem- A checkbox item. This only differs from the plain list
item by the default template.
table-line- a new line in the first table at the target location.
Where exactly the line will be inserted depends on the
properties
:prepend and
:table-line-pos (see below).
plain- Text to be inserted as it is.
- target
-
Specification
of where the captured item should be placed. In Org-mode
files, targets usually define a node. Entries will become
children of this node. Other types will be added to the table
or list in the body of this node. Most target specifications
contain a file name. If that file name is the empty string,
it defaults to
org-default-notes-file.
Valid values are:
(file "path/to/file")- Text will be placed at the beginning or end of that
file.
(id "id of existing org entry")- Filing as child of this entry, or in the body of the
entry.
(file+headline "path/to/file" "node
headline")- Fast configuration if the target heading is unique in
the file.
(file+olp "path/to/file" "Level 1 heading" "Level
2" ...)- For non-unique headings, the full path is
safer.
(file+regexp "path/to/file" "regexp to find
location")- Use a regular expression to position the
cursor.
(file+datetree "path/to/file")- Will create a heading in a date tree for today's
date.
(file+datetree+prompt "path/to/file")- Will create a heading in a date tree, but will prompt
for the date.
(file+function "path/to/file"
function-finding-location)- A function to find the right location in the
file.
(clock)- File to the entry that is currently being
clocked.
(function function-finding-location)- Most general way, write your own function to find both
file and location.
- template
- The template for creating the capture item. If you leave
this empty, an appropriate default template will be used.
Otherwise this is a string with escape codes, which will be
replaced depending on time and context of the capture call. The
string with escapes may be loaded from a template file, using
the special syntax
(file "path/to/template"). See
below for more details.
- properties
-
The rest of the entry is a property list of additional
options. Recognized properties are:
:prepend- Normally new captured information will be appended at
the target location (last child, last table line, last list
item...). Setting this property will change
that.
:immediate-finish- When set, do not offer to edit the information, just
file it away immediately. This makes sense if the template
only needs information that can be added
automatically.
:empty-lines- Set this to the number of lines to insert before and
after the new item. Default 0, only common other value is
1.
:clock-in- Start the clock in this item.
:clock-resume- If starting the capture interrupted a clock, restart
that clock when finished with the capture.
:unnarrowed- Do not narrow the target buffer, simply show the full
buffer. Default is to narrow it so that you only see the
new material.
:kill-buffer- If the target file was not yet visited when capture was
invoked, kill the buffer again after capture is
completed.